<!DOCTYPE html PUBLIC "-//W3C//DTD XHTML 1.0 Strict//EN"
   "http://www.w3.org/TR/xhtml1/DTD/xhtml1-strict.dtd">
<html>
<meta http-equiv="Content-Type" content="text/html; charset=UTF-8"/>
<head>
    <title>Extended timer for OpenResty</title>
    <link rel="stylesheet" href="ldoc.css" type="text/css" />
</head>
<body>

<div id="container">

<div id="product">
	<div id="product_logo"></div>
	<div id="product_name"><big><b></b></big></div>
	<div id="product_description"></div>
</div> <!-- id="product" -->


<div id="main">


<!-- Menu -->

<div id="navigation">
<br/>
<h1>lua-resty-timer</h1>


<h2>Contents</h2>
<ul>
<li><a href="#Functions">Functions</a></li>
</ul>


<h2>Modules</h2>
<ul class="nowrap">
  <li><strong>resty.timer</strong></li>
</ul>
<h2>Topics</h2>
<ul class="">
  <li><a href="topics/README.md.html">README</a></li>
</ul>

</div>

<div id="content">

<h1>Module <code>resty.timer</code></h1>
<p>Extended timer.</p>
<p> Provides recurring, cancellable, node-wide timers, beyond
 what the basic OpenResty timers do.</p>
    <h3>Info:</h3>
    <ul>
        <li><strong>Copyright</strong>: 2017 - 2020 Kong Inc.</li>
        <li><strong>License</strong>: Apache 2.0</li>
        <li><strong>Author</strong>: Thijs Schreijer</li>
    </ul>


<h2><a href="#Functions">Functions</a></h2>
<table class="function_list">
	<tr>
	<td class="name" nowrap><a href="#cancel">cancel ()</a></td>
	<td class="summary">Cancel the timer.</td>
	</tr>
	<tr>
	<td class="name" nowrap><a href="#new">new (opts, ...)</a></td>
	<td class="summary">Create a new timer.</td>
	</tr>
</table>

<br/>
<br/>


    <h2 class="section-header "><a name="Functions"></a>Functions</h2>

    <dl class="function">
    <dt>
    <a name = "cancel"></a>
    <strong>cancel ()</strong>
    </dt>
    <dd>
    Cancel the timer.
 Will run the 'cancel'-callback if provided. Will only cancel the timer
 in the current worker.



    <h3>Returns:</h3>
    <ol>

        results of the 'cancel' callback, or <code>true</code> if no callback was provided
 or <code>nil + &quot;already cancelled&quot;</code> if called repeatedly
    </ol>



    <h3>Usage:</h3>
    <ul>
        <pre class="example"><span class="keyword">local</span> t, err = resty_timer(options)  <span class="comment">-- create a timer
</span><span class="keyword">if</span> t <span class="keyword">then</span>
  t:cancel()  <span class="comment">-- immediately cancel the timer again
</span><span class="keyword">end</span></pre>
    </ul>

</dd>
    <dt>
    <a name = "new"></a>
    <strong>new (opts, ...)</strong>
    </dt>
    <dd>

<p>Create a new timer.
 The <code>opts</code> table is not stored nor altered, and can hence be safely reused to
 create multiple timers. It supports the following parameters:</p>

<ul>
    <li><p><code>interval</code> : (number) interval in seconds after which the timer expires</p></li>
    <li><p><code>recurring</code> : (boolean) set to <code>true</code> to make it a recurring timer</p></li>
    <li><p><code>jitter</code> : (optional, number) variable interval to add to the first interval, default 0.
    If set to 1 second then the first interval will be set between <code>interval</code> and <code>interval + 1</code>.
    This makes sure if large numbers of timers are used, their execution gets randomly
    distributed.</p></li>
    <li><p><code>immediate</code> : (boolean) will do the first run immediately (the initial
    interval will be set to 0 seconds). This option requires the <code>recurring</code> option.
    The first run will not include the <code>jitter</code> interval, it will be added to second run.</p></li>
    <li><p><code>detached</code> : (boolean) if set to <code>true</code> the timer will keep running detached, if
    set to <code>false</code> the timer will be garbage collected unless anchored
    by the user.</p></li>
    <li><p><code>expire</code> : (function) callback called as <code>function(...)</code> with the arguments passed
    as extra beyond the <code>opts</code> table to this <a href="index.html#new">new</a> function.</p></li>
    <li><p><a href="index.html#cancel">cancel</a> : (optional, function) callback called as <code>function(reason, ...)</code>. Where
    <code>reason</code> indicates why it was cancelled. The additional arguments will be the
    arguments as passed to this <a href="index.html#new">new</a> function, beyond the <code>opts</code> table. See the
    usage example below for possible values for <code>reason</code>.</p></li>
    <li><p><code>shm_name</code> : (optional, string) name of the shm to use to synchronize with the
    other workers if <code>key_name</code> is set.</p></li>
    <li><p><code>key_name</code> : (optional, string) key name to use in shm <code>shm_name</code>. If this key is given
    the timer will only be executed in a single worker. All timers (across all workers) with the same
    key will share this. The key will always be prefixed with this module's
    name to prevent name collisions in the shm. This option requires the <code>shm_name</code> option.</p></li>
    <li><p><code>sub_interval</code> : (optional, number) interval in seconds to check whether
    the timer needs to run. Only used for cross-worker timers. This setting reduces
    the maximum delay when a worker that currently runs the timer exits. In this case the
    maximum delay could be <code>interval * 2</code> before another worker picks it up. With
    this option set, the maximum delay will be <code>interval + sub_interval</code>.
    This option requires the <code>immediate</code> and <code>key_name</code> options.</p></li>
</ul>




    <h3>Parameters:</h3>
    <ul>
        <li><span class="parameter">opts</span>
         table with options
        </li>
        <li><span class="parameter">...</span>
         arguments to pass to the callbacks <code>expire</code> and <a href="index.html#cancel">cancel</a>.
        </li>
    </ul>

    <h3>Returns:</h3>
    <ol>

        <a href="index.html">timer</a> object or <code>nil + err</code>
    </ol>



    <h3>Usage:</h3>
    <ul>
        <pre class="example"><span class="keyword">local</span> object = {
  name = <span class="string">"myName"</span>,
}

<span class="keyword">function</span> object:timer_callback(...)
  <span class="comment">-- Note: here we use colon-":" syntax
</span>  <span class="global">print</span>(<span class="string">"starting "</span>, self.name, <span class="string">": "</span>, ...)   <span class="comment">--&gt; "starting myName: 1 two 3"
</span><span class="keyword">end</span>

<span class="keyword">function</span> object.cancel_callback(reason, self, ...)
  <span class="comment">-- Note: here we cannot use colon-":" syntax, due to the 'reason' parameter
</span>  <span class="global">print</span>(<span class="string">"stopping "</span>, self.name, <span class="string">": "</span>, ...)   <span class="comment">--&gt; "stopping myName: 1 two 3"
</span>  <span class="keyword">if</span> reason == resty_timer.CANCEL_USER <span class="keyword">then</span>
    <span class="comment">-- user called <a href="index.html#cancel">timer:cancel</a>
</span>  <span class="keyword">elseif</span> reason == resty_timer.CANCEL_GC <span class="keyword">then</span>
    <span class="comment">-- the timer was garbage-collected
</span>  <span class="keyword">elseif</span> reason == resty_timer.CANCEL_SYSTEM <span class="keyword">then</span>
    <span class="comment">-- prematurely cancelled by the system (worker is exiting)
</span>  <span class="keyword">else</span>
    <span class="comment">-- should not happen
</span>  <span class="keyword">end</span>
<span class="keyword">end</span>

<span class="keyword">function</span> object:start()
  <span class="keyword">if</span> self.timer <span class="keyword">then</span> <span class="keyword">return</span> <span class="keyword">end</span>
  self.timer = resty_timer({
    interval = <span class="number">1</span>,
    expire = self.timer_callback,
    cancel = self.cancel_callback,
  }, self, <span class="number">1</span>, <span class="string">" two "</span>, <span class="number">3</span>)  <span class="comment">-- 'self' + 3 parameters to pass to the callbacks
</span>
<span class="keyword">function</span> object:stop()
  <span class="keyword">if</span> self.timer <span class="keyword">then</span>
    self.timer:cancel()
    self.timer = <span class="keyword">nil</span>
  <span class="keyword">end</span>
<span class="keyword">end</span></pre>
    </ul>

</dd>
</dl>


</div> <!-- id="content" -->
</div> <!-- id="main" -->
<div id="about">
<i>generated by <a href="http://github.com/stevedonovan/LDoc">LDoc 1.4.6</a></i>
<i style="float:right;">Last updated 2020-11-07 00:01:15 </i>
</div> <!-- id="about" -->
</div> <!-- id="container" -->
</body>
</html>
